<?xml version="1.0" encoding="utf-8"?>
<!--
                                                                                     
 h       t     t                ::       /     /                     t             / 
 h       t     t                ::      //    //                     t            // 
 h     ttttt ttttt ppppp sssss         //    //  y   y       sssss ttttt         //  
 hhhh    t     t   p   p s            //    //   y   y       s       t          //   
 h  hh   t     t   ppppp sssss       //    //    yyyyy       sssss   t         //    
 h   h   t     t   p         s  ::   /     /         y  ..       s   t    ..   /     
 h   h   t     t   p     sssss  ::   /     /     yyyyy  ..   sssss   t    ..   /     
                                                                                     
	<https://y.st./>
	Copyright © 2017 Alex Yst <mailto:copyright@y.st>

	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 3 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program. If not, see <https://www.gnu.org./licenses/>.
-->
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<base href="https://y.st./en/weblog/2017/09-September/01.xhtml"/>
		<title>include.d version 0.0.1.6 &lt;https://y.st./en/weblog/2017/09-September/01.xhtml&gt;</title>
		<link rel="icon" type="image/png" href="/link/CC_BY-SA_4.0/y.st./icon.png"/>
		<link rel="stylesheet" type="text/css" href="/link/main.css"/>
		<script type="text/javascript" src="/script/javascript.js"/>
		<meta name="viewport" content="width=device-width"/>
	</head>
	<body>
<nav>
	<p>
		<a href="/en/coursework/">Coursework</a> |
		<a href="/en/take-down/">Take-down requests</a> |
		<a href="/en/">Home</a> |
		<a href="/en/a/about.xhtml">About</a> |
		<a href="/en/a/contact.xhtml">Contact</a> |
		<a href="/a/canary.txt">Canary</a> |
		<a href="/en/URI_research/"><abbr title="Uniform Resource Identifier">URI</abbr> research</a> |
		<a href="/en/opinion/">Opinions</a> |
		<a href="/en/law/">Law</a> |
		<a href="/en/recipe/">Recipes</a> |
		<a href="/en/a/links.xhtml">Links</a> |
		<a href="/en/weblog/2017/09-September/01.xhtml.asc">{this page}.asc</a>
	</p>
	<hr/>
	<p>
		Weblog index:
		<a href="/en/weblog/memories">Memories</a> |
		<a href="/en/weblog/"><abbr title="American Standard Code for Information Interchange">ASCII</abbr> calendars</a> |
		<a href="/en/weblog/index_ol_ascending.xhtml">Ascending list</a> |
		<a href="/en/weblog/index_ol_descending.xhtml">Descending list</a>
	</p>
	<hr/>
	<p>
		Jump to entry:
		<a href="/en/weblog/2015/03-March/07.xhtml">&lt;&lt;First</a>
		<a rel="prev" href="/en/weblog/2017/08-August/31.xhtml">&lt;Previous</a>
		<a rel="next" href="/en/weblog/2017/09-September/02.xhtml">Next&gt;</a>
		<a href="/en/weblog/latest.xhtml">Latest&gt;&gt;</a>
			</p>
			<hr/>
</nav>
		<header>
			<h1>include.d version 0.0.1.6</h1>
			<p>Day 00909: <time>Friday, 2017 September 01</time></p>
		</header>
<section id="to-do">
	<h2>To-do list</h2>
	<ul>
		<li>
			Acquire stuff for my new home:
			<ul>
				<li>
					A bed
				</li>
				<li>
					A dustpan
				</li>
				<li>
					A carpet broom
				</li>
			</ul>
		</li>
		<li>
			Inform people that I&apos;ve moved
			<ul>
				<li>
					Relevant online accounts
				</li>
			</ul>
		</li>
		<li>
			<del>Finish stabilizing <a href="https://git.volatile.ch./y.st./include.d/releases">include.d</a> and put out another release (low priority)</del>
		</li>
		<li>
			Clean up my apartment
			<ul>
				<li>
					Clean up the kitchen
				</li>
			</ul>
		</li>
	</ul>
</section>
<section id="general">
	<h2>General news</h2>
	<p>
		The new system at work is a total mess.
		At one point, we had to stop allowing customers to place custom orders.
		Custom pizzas weren&apos;t showing up in the system, so we had to sell only the types of pizzas we keep pre-made.
		One customer at the drive-through even left without buying anything because we weren&apos;t able to take requests like we normally do.
		Once the rush was over, we started taking custom orders again, but we had to not only enter them into the computer like we&apos;re supposed to, but additionally write out paper tickets for them like we used to.
		The paper tickets, unlike the digital ones, don&apos;t get lost until we intentionally throw them away when we&apos;re done with them.
		At the end of the night, the head manager was holding back complaints about the new system, but they did surface a little.
		I mentioned that I&apos;d love to know whether it was the franchise owner or corporate that decided upon this change.
		I never thought I&apos;d get the answer, but it seems the head manager was in the know.
		The franchise owner never wanted this, though they did try to be optimistic about it.
		Come to think of it, that would be the most in-character position for the franchise owner to take.
		They don&apos;t like to replace anything until it&apos;s absolutely unusable, for example, because they like to try to save every penny they can.
		All the equipment for the new system alone would&apos;ve cost a fortune, not to mention the cost software.
		Corporate probably sold the franchise owner this mandatory software for a small fortune as well, and that&apos;s probably why corporate even demanded the change.
		They just wanted to squeeze more money out of their franchise owners.
	</p>
	<p>
		At first, upon hearing this, I thought it was very wrong for corporate to force this proprietary new system on the franchise owner.
		The franchise owner likely doesn&apos;t care about freedom, but if they did, they should be able to opt out of this.
		But then it hit me.
		Everything about this brand is proprietary.
		There&apos;s so many proprietary trade secrets and other garbage going on.
		If the franchise owner cared anything about freedom, they wouldn&apos;t&apos;ve signed up to run a franchise of this brand (or likely, a franchise of anything at all; they&apos;d start their own brand).
		They sold away all rights to claim a desire for freedom when they took on corporate&apos;s name.
	</p>
	<p>
		My <a href="/a/canary.txt">canary</a> still sings the tune of freedom and transparency.
	</p>
</section>
<section id="include.d">
	<h2><a href="https://git.volatile.bz./y.st./include.d/releases">include.d</a></h2>
	<p>
		phpDocumentor was problematic when I last used it successfully.
		First, I found it threw errors with certain perfectly-valid <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> syntax.
		Instead of handling <strong>*only*</strong> documentation comments, phpDocumentor also parses the entire file and does stuff with other information found there too.
		That&apos;s probably a good thing, aside from the fact that phpDocumentor doesn&apos;t seem to get updated often to support new syntax as it comes out.
		Second, the code was confusing and I had no idea how to get my own templates implemented.
		As a result, the output documentation pages were overly complex and required JavaScript to function.
		I was planning on eventually setting up my own replacement for phpDocumentor, but maybe it&apos;s time to bump that project up in my schedule.
		Maybe I should work on that now instead of the Web server I want to build.
	</p>
	<p>
		Since I&apos;m building my own documentation generator, I&apos;ll put off testing the thrown exceptions for now.
		The main reason I wanted to be sure to test them all was to make sure the documentation file on exception codes is accurate.
		This file is automatically generated, so I wanted to be sure that all places in the code that throw exceptions can actually be reached.
		I&apos;ll make that a part of my documentation-related task list.
	</p>
	<p>
		I&apos;ve released the new version on both NotABug and Volatile Git.
	</p>
	<p>
		I&apos;ve started planning how I want my documentor to function.
		For one thing, I want it to run a bunch of sanity checks on the code; in particular, the method signatures.
		All parameters and return values should have type hints, for example.
		If I forget a type hint, I want the documentor to catch my mistake and throw an exception.
		(This should be configurable and disabled by default, but I&apos;d turn it on for constructing my own documentation.)
		This does cause some issues though.
	</p>
	<p>
		The first problem area is built-in interfaces.
		Built-in language interfaces usually have some sort of special quality they bestow on the classes that implement them, a quality not otherwise obtainable and not able to be replicated.
		However, the method signatures belonging to those interfaces don&apos;t use type hints, so if type hints are used with the parameters of the actual method implementations, the code won&apos;t run.
		So if I use type hints, the code will break, but if I don&apos;t use type hints, the documentation will break.
		I looked for a way to detect the method signatures of traits from the documentor, which would allow the documentor to be less strict when a class is trying to implement interfaces that don&apos;t use type hints, but I never could find a way.
		However, I found a way to detect when an interface is built-in instead of implemented in <abbr title="PHP: Hypertext Preprocessor">PHP</abbr>.
		With some testing, I found that for some reason, if an interface implements type hints in the parameter specifications, the implementation also must, or the code won&apos;t run.
		This is inconsistent, seeing as when an interface requires a method accept certain arguments, the actual implementation is able to make those arguments optional.
		In other words, to be consistent, the type hints shouldn&apos;t be mandatory in the implementation, because if no type hints are used, the method&apos;s still able to accept everything that the interface requires it to, but it can also accept other values just like it can accept a lack of values when it makes a parameter optional.
		However, in my case, this strangeness works out well.
		It means the interface, although it fails to use type hinting, will police the methods that implement it for me.
		If the interface ever changes and uses type hinting, my code will break and I&apos;ll know to add the type hinting that I&apos;d already like to add.
		That said, because it&apos;d break the code, it&apos;ll probably never happen.
		The <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> crew usually tries to avoid breaking compatibility with older code, so these interfaces will probably never have type hints.
		To avoid the option of setting up userspace interfaces to avoid type hints, only interfaces that exist outside userspace will be granted the ability to provide exceptions for implementations.
	</p>
	<p>
		The second issue is callback functions and resource handles.
		Sometimes, a function needs to be registered as a callback function, in which case it needs to be able to accept very specific types of arguments.
		This is all well and good, and in theory, the callback function would work equally well whether the correct type hints or no type hints are used, as long as the <strong>*incorrect*</strong> type hints aren&apos;t used.
		So I could use the type hinting I want to use and that will be enforced by the documentor&apos;s strict mode.
		However, resource handles can&apos;t be type hinted for.
		The only parameters that accept resource handles are those that accept arguments of any possible value.
		There&apos;s absolutely no way to detect in an automated way that a function is meant to be a callback for something that will pass a resource handle.
		I eventually found a solution to that issue as well, though it&apos;s not one I&apos;m particularly happy with.
		I&apos;d planned to remove parameter types from the documentation comments.
		After all, that information could be obtained by the documentor from the code itself via the type hints.
		However, by keeping the type hints redundantly documented in the comments, I can use a special flag to allow exceptions.
		This has advantages in keeping the documentation correct, too.
		If I change a method signature, but mess up and forget to update the argument documentation, the documentor can catch the mismatch and throw an exception.
		The part I don&apos;t like though is where this allows any argument in the entire library, regardless of the use of that particular function/method, to gain an exception.
		However, it is what it is, and it&apos;s probably what I&apos;m going to do, at least until a time when all argument types can be hinted for or a &quot;mixed&quot; key word or some such is provided to explicitly tell <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> that all values are allowed.
		The <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> manual seems to hint that both the <code>resource</code> and <code>mixed</code> key words may one day be provided.
		With exceptions being granted from the documentation comments themselves, it becomes redundant to try to detect built-in interfaces.
		Exceptions for these methods simply need to be documented in the comments just like for the callback functions, at least, again, until the required features are provided to make implementations of built-in interfaces the only case in which type hints shouldn&apos;t be used.
	</p>
	<p>
		At first, I was going to use <code>mixed</code> as a special value to indicate that an argument was exempt from type hinting.
		However, it&apos;s possible a class of that name could be defined, and it&apos;d need to be possible for the documentor to keep these two cases separate in every way.
		Obviously, the documentor could tell the difference based on whether the actual <code>mixed</code> type hint, which for now would be interpreted by <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> as being a class name, was present in the code.
		However, if the argument was switched between these two cases and the documentation not updated, an exception should be thrown to alert the programmer that they forgot to update the docs, but this exception would never come.
		I considered several special values, including <code>*mixed*</code> for interface usage and <code>*resource*</code> for callbacks that need to accept a resource handle.
		Because of the asterisks in the values, they&apos;d never match any class names.
		However, these two values take on the exact same purpose, they just hint to the reader what the intention is.
		I decided to go with a single value, that of a single asterisk, to indicate to the documentor any case in which it should expect to see no type hint with an argument.
		If a type hint is seen anyway when an asterisk is used, that should throw an exception just as having no type hint without an asterisk in the documentation or having the wrong type hint would.
		The single asterisk will simply be the way of indicating that the intention is that there be no type hint.
		This won&apos;t work with return values though.
		All return values must be type hinted for.
	</p>
	<p>
		Later, I realised I could&apos;ve used a <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> key word instead of an asterisk to achieve the same thing.
		I couldn&apos;t use <code>parent</code> or <code>self</code>, as those both hold special meaning in type hints.
		However, a comment type hint of <code>interface</code> to indicate that a parameter must not have a type hint because of an interface it implements or a comment type hint of <code>var</code> to indicate that a parameter can accept any variable would work well.
		I decided to stick with the asterisk for now though.
		It&apos;s easily recognisable and should never clash with any <abbr title="PHP: Hypertext Preprocessor">PHP</abbr> feature in the future.
	</p>
</section>
		<hr/>
		<p>
			Copyright © 2017 Alex Yst;
			You may modify and/or redistribute this document under the terms of the <a rel="license" href="/license/gpl-3.0-standalone.xhtml"><abbr title="GNU&apos;s Not Unix">GNU</abbr> <abbr title="General Public License version Three or later">GPLv3+</abbr></a>.
			If for some reason you would prefer to modify and/or distribute this document under other free copyleft terms, please ask me via email.
			My address is in the source comments near the top of this document.
			This license also applies to embedded content such as images.
			For more information on that, see <a href="/en/a/licensing.xhtml">licensing</a>.
		</p>
		<p>
			<abbr title="World Wide Web Consortium">W3C</abbr> standards are important.
			This document conforms to the <a href="https://validator.w3.org./nu/?doc=https%3A%2F%2Fy.st.%2Fen%2Fweblog%2F2017%2F09-September%2F01.xhtml"><abbr title="Extensible Hypertext Markup Language">XHTML</abbr> 5.2</a> specification and uses style sheets that conform to the <a href="http://jigsaw.w3.org./css-validator/validator?uri=https%3A%2F%2Fy.st.%2Fen%2Fweblog%2F2017%2F09-September%2F01.xhtml"><abbr title="Cascading Style Sheets">CSS</abbr>3</a> specification.
		</p>
	</body>
</html>

